Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 2 - Control Manager Reference / Control Manager Functions

Defining Your Own Key Filter Function /

MyControlKeyFilterProc

NEW WITH THE APPEARANCE MANAGER

Controls that support text input (such as editable text and list box controls) can attach a key filter function to filter key strokes and modify them on return.

The Control Manager declares the type for an application-defined key filter function as follows:

typedef pascal KeyFilterResult (*ControlKeyFilterProcPtr)(
                                 ControlHandle theControl,
                                 SInt16* keyCode,
                                 SInt16* charCode,
                                 SInt16* modifiers);

The Control Manager defines the data type ControlKeyFilterUPP to identify the universal procedure pointer for this application-defined function:

typedef UniversalProcPtr ControlKeyFilterUPP;

You typically use the NewControlKeyFilterProc macro like this:

NewControlKeyFilterUPP myControlKeyFilterUPP;
myControlKeyFilterUPP = NewControlKeyFilterProc(MyKeyFilter);

You typically use the CallControlKeyFilterProc macro like this:

CallControlKeyFilterProc(myControlKeyFilterUPP, theControl, keyCode, charCode, modifiers);

Here's how to declare a key filter function if you were to name the function MyControlKeyFilterProc:

pascal ControlKeyFilterResult MyControlKeyFilterProc (
                     ControlHandle theControl, 
                     SInt16* keyCode,
                     SInt16* charCode,
                     SInt16* modifiers);

theControl

A handle to the control in which the mouse-down event occurred.

keyCode

The virtual key code derived from the event structure. This value represents the key pressed or released by the user. It is always the same for a specific physical key on a particular keyboard regardless of which modifier keys were also pressed.

charCode

A particular character derived from the event structure. This value depends on the virtual key code, the state of the modifier keys, and the current 'KCHR' resource.

modifiers

The constant in the modifiers field of the event structure specifying the state of the modifier keys and the mouse button at the time the event was posted.

function result

Returns a value indicating whether or not it allowed or blocked keystrokes; see "Key Filter Result Codes".

DISCUSSION

Your key filter function can intercept and change keystrokes destined for a control. Your key filter function can change the keystroke, leave it alone, or block your control definition function from receiving it. For example, an editable text control can use a key filter function to allow only numeric values to be input in its field.

Key Filter Result Codes

Your key filter function returns these constants to specify whether or not a keystroke is filtered or blocked.

enum {
   kControlKeyFilterBlockKey= 0,
   kControlKeyFilterPassKey= 1
};
typedef SInt16 ControlKeyFilterResult;

Constant descriptions

kControlKeyFilterBlockKey

The keystroke is blocked and not received by the control.

kControlKeyFilterPassKey

The keystroke is filtered and received by the control.